---

Adding Custom Controls

The Navigation Services programming interface handles most common situations that demand interface customization when using the Standard File Package. If you look through all the features and find that you still need to provide custom controls in a Navigation Services dialog box, perform the following steps:

1. Implement an event-handling function to communicate with Navigation Services while Open or Save dialog boxes are open. For more information, see Handling Events.
2. Respond to the kNavCBCustomize constant, described in , which your application can obtain from the param field of the structure of type pointed to in the callBackParms parameter of your event-handling function. The customRect field of the structure defines a rectangle in the local coordinates of the window; the top-left coordinates define the anchor point for the customization rectangle, which is the area Navigation Services provides for your application to add custom dialog box items. Your application responds by setting the values which complete the dimensions of the customization rectangle you require in the customRect field of the structure. After your application responds and exits from the event-handling function, Navigation Services inspects the customRect field to determine if the requested dimensions result in a dialog window that can fit on the screen. If the resulting window dimensions are too large, then Navigation Services responds by setting the rectangle to the largest size that can be accommodated and notifying your application with the kNavCBCustomize constant again. Your application can continue to negotiate with Navigation Services by examining the customRect field and requesting a different size until Navigation Services provides an acceptable rectangle value.
   The minimum dimensions for the customization area are 400 pixels wide by 40 pixels high on a 600 x 400 pixel screen. If you are designing for a minimum screen size of 640 x 480 or larger, you can assume a larger minimum customization area.
3. After a customization rectangle has been established, your application must check for the kNavCBStart constant in the param field of the structure. This constant indicates that Navigation Services is opening the dialog box. After you obtain this constant, you can add your interface elements to the customization rectangle. The simplest way to do this is to provide a 'DITL' resource (in local coordinates, relative to the anchor point of the customization rectangle) and pass the kNavCtlAddControlList constant in the selector parameter of the function . Listing 2-4 illustrates one way to do this.

   Listing 2-4	Adding a custom 'DITL' resource
   gDitlList = GetResource ('DITL', kControlListID);
   theErr = NavCustomControl   (callBackParms->context, 
                               kNavCtlAddControlList, gDitlList);
   

The advantage of using a 'DITL' resource is that the Dialog Manager handles all control movement and tracking.

You can also draw a single control by calling the Control Manager function NewControl and passing the kNavCtlAddControl constant, described in , in the selector parameter of the function . Listing 2-5 illustrates this approach.

Listing 2-5	Adding a single custom control
gCustomControl = NewControl (callBackParms->window, &itemRect, 
                "\pcheckbox", false, 1, 0, 1, checkBoxProc, NULL);
theErr = NavCustomControl (callBackParms->context, kNavCtlAddControl,
                            gCustomControl);

If you call NewControl , you must track the custom control yourself.

4. Navigation Services supplies the kNavCBTerminate constant in the param field of the structure after the user closes the dialog box. Make sure you check for this constant, which is your signal to dispose of your control or resource.